<html>
<head><meta charset="utf-8"><title>Rust Design Patterns · t-libs · Zulip Chat Archive</title></head>
<h2>Stream: <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/index.html">t-libs</a></h2>
<h3>Topic: <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Rust.20Design.20Patterns.html">Rust Design Patterns</a></h3>

<hr>

<base href="https://rust-lang.zulipchat.com">

<head><link href="https://rust-lang.github.io/zulip_archive/style.css" rel="stylesheet"></head>

<a name="221866850"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/219381-t-libs/topic/Rust%20Design%20Patterns/near/221866850" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> simonsan <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Rust.20Design.20Patterns.html#221866850">(Jan 07 2021 at 08:19)</a>:</h4>
<p>Hello everyone, one (newly assigned) maintainer of the <a href="https://github.com/rust-unofficial/patterns">Rust Design patterns</a> book here. :)</p>
<p><a href="https://www.reddit.com/r/rust/comments/kowtqn/rust_design_patterns_now_also_as_a_book/gic8knd/?utm_source=reddit&amp;utm_medium=web2x&amp;context=3">This comment</a> brought me here.</p>



<a name="221975841"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/219381-t-libs/topic/Rust%20Design%20Patterns/near/221975841" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> simonsan <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Rust.20Design.20Patterns.html#221975841">(Jan 07 2021 at 17:49)</a>:</h4>
<p>Oh, I just saw now, that only a part of my comment was sent.  :(</p>
<p>My question was if there would be any (future?) interest from the t-libs team to bring the pattern book into <code>rust-lang</code> and put it aside the API guidelines? Or is there any other plan what should happen with <code>rust-unofficial</code> in general?</p>



<a name="221986479"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/219381-t-libs/topic/Rust%20Design%20Patterns/near/221986479" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Lokathor <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Rust.20Design.20Patterns.html#221986479">(Jan 07 2021 at 19:08)</a>:</h4>
<p>I am not on T-libs, but I suspect that each book would be moved on a case by case basis.</p>



<a name="222046747"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/219381-t-libs/topic/Rust%20Design%20Patterns/near/222046747" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Ashley Mannix <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Rust.20Design.20Patterns.html#222046747">(Jan 08 2021 at 08:15)</a>:</h4>
<p>Hey <span class="user-mention" data-user-id="377077">@simonsan</span> ! Welcome <span aria-label="wave" class="emoji emoji-1f44b" role="img" title="wave">:wave:</span> So to catch you up on where we've been at with the <a href="https://github.com/rust-lang/api-guidelines">API Guidelines</a>, it's been sitting in a basically "done" state for a couple years, but things change and it's getting due for a refresh. One issue we ran into with the Guidelines was that people want to talk about them (that's not the issue), and that discussion is a useful resource in its own right even if it doesn't conclude with a new concrete guideline. That kind of UX hasn't traditionally worked well in GitHub, but could be nice in discussions. So we've got <a href="https://github.com/rust-lang/libs-team/pull/6">an active proposal</a> to revive the API Guidelines using GitHub discussions and keeping issues and PRs for concrete action items.</p>
<p>Where I think the Design patterns comes in is a fair amount of discussion on API Guidelines is actually about patterns instead. Some of it affects public API, but isn't targeted enough to be considered a guideline. I imagine there is enough overlap though that it could be worth sharing a single discussion source for both.</p>
<p>Going even further than that, I think there's probably room for a Patterns and Guidelines team that focuses on curating these resources we're building.</p>
<p>I'd love to get your thoughts on what direction you'd like to take the Patterns Book in, and whether you've got thoughts on the Guidelines too!</p>



<a name="222056451"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/219381-t-libs/topic/Rust%20Design%20Patterns/near/222056451" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> simonsan <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Rust.20Design.20Patterns.html#222056451">(Jan 08 2021 at 10:24)</a>:</h4>
<p><span class="user-mention silent" data-user-id="204346">Ashley Mannix</span> <a href="#narrow/stream/219381-t-libs/topic/Rust.20Design.20Patterns/near/222046747">said</a>:</p>
<p>Hey Ashley,<br>
huge topic(s) :D</p>
<p>First of all, thank you for bringing me up-to-date to the current stage of discussion. And I need to say, that I'm not an English native speaker, so excuse me if some things are stated unclear in the following text:</p>
<blockquote>
<p>So to catch you up on where we've been at with the API Guidelines, it's been sitting in a basically "done" state for a couple years, but things change and it's getting due for a refresh. One issue we ran into with the Guidelines was that people want to talk about them (that's not the issue), and that discussion is a useful resource in its own right even if it doesn't conclude with a new concrete guideline.</p>
</blockquote>
<p>I think that these are really important aspects you are mentioning here.</p>
<p>First, the stage of completeness/amount of correctness.<br>
Secondly, the need for a "small" refresh.<br>
Third, the need for discussions and thus community participation on changes to these API guidelines. </p>
<p>Let me compare that directly to the patterns to get a clearer view, where it stands in my opinion:</p>
<ul>
<li>
<p>First, the patterns are not at any stage of completeness nor at a general stage of overall correctness (FFI section is currently undergoing a second rework and will probably get many more). They are more "opinionated" than the API guidelines, from my point of view.</p>
</li>
<li>
<p>Second point, they are continuously evolving by community input, as in some kind of a peer reviewing process. We are trying to sort out errors or out-of-scope topics in Pull Requests and help fixing them to our best knowledge. That said, we rely on the participation of people with more expertise in their field (e.g. FFI). So it is not guaranteed that everything is "perfect". It's more getting to the "best practices" asymptotically. At one point, we will have a learning resource at hand that many eyes read over and fixed inconsistencies, error or added new implicit knowledge of themselves. The API guidelines are more stable, so to say, while the patterns in this stage are more on a "rolling release" model (not the best picture). I described them in our contribution guidelines as <code>a compilation of collective (sometimes implicit) knowledge as well as experiences that have emerged through collaborative work</code>. It would maybe even make sense to SemVer the API guidelines.</p>
</li>
<li>
<p>Third, through this approach, which differs substantially from the API guidelines (correct me if I'm assuming something here, that's not true), there are traditionally also more discussions on certain aspects for the patterns and the reliance on the community and collective work to fix things/give feeback/input is bigger.</p>
</li>
</ul>
<blockquote>
<p>That kind of UX hasn't traditionally worked well in GitHub, but could be nice in discussions. So we've got an active proposal to revive the API Guidelines using GitHub discussions and keeping issues and PRs for concrete action items.</p>
</blockquote>
<p>Agreed, that's the <a href="https://github.com/rust-unofficial/patterns/blob/master/CONTRIBUTING.md">same approach the patterns repository is taking</a>. For now discussions are still in issues though, as it's quite new and the GH discussions are still in beta and it's not sure, how they will evolve. Also I see a problem with platform lock-in. As it might make sense to have the discussions where the data is, relying solely on discussions on the same platform might be not the best approach long-term - but indeed it is the one with the lowest barrier of entry as people contributing to the repository already have a Github account.</p>
<blockquote>
<p>Where I think the Design patterns comes in is a fair amount of discussion on API Guidelines is actually about patterns instead. Some of it affects public API, but isn't targeted enough to be considered a guideline. I imagine there is enough overlap though that it could be worth sharing a single discussion source for both.</p>
</blockquote>
<p>Agreed as well, though I'm not sure if Github discussions is the best then for a "single source of discussions" principle, as that would mean, we need to merge the repositories or link to another repository's discussion platform, which might(?) be confusing for the people.</p>
<blockquote>
<p>Going even further than that, I think there's probably room for a Patterns and Guidelines team that focuses on curating these resources we're building. I'd love to get your thoughts on what direction you'd like to take the Patterns Book in, and whether you've got thoughts on the Guidelines too!</p>
</blockquote>
<p>Ok, let me build describe my utopia here and dream a bit:</p>
<p>Rust as a low-barrier ecosystem to oldschool programmers and Rustlings alike. Having a great amount of FLOSS resources to learn it and get better at it managed by a group of people that have the overview over it and could easily share the information between the ressources. Easy to navigate, sensefully ordered for different stages of prerequisites (or expected knowledge). Kind of a compendium that is not overwhelming and building up knowledge in how to design software with Rust.</p>
<p>That said, I'm unsure how low-level (from the programming point of view, not from the expected knowledge and barrier of entry) the patterns and API guidelines are or how much they differ in that aspect.</p>
<p>Regarding the patterns book I would love to give people input on common software design practices and how they are done in idiomatic Rust, so people have a small learning platform/book at hand like "Design Patterns" (Gamma, Helm, Johnson, Vlissides) for this language giving good (or best) practices for patterns, anti-patterns, idioms, functional programming in Rust and how the process of refactoring could be done in Rust. <code>A helpful guide to Software Design in Rust.</code>, though I'm not sure if that scope isn't a bit too big outside of my dream.</p>
<p>Another idea for barriers of entry for the far future was for example, to have a small tool at hand like an <code>mdbook-reader</code> that can pull in different books and print chapters (short versions of them) to the terminal in your IDE to have easy access to the information contained in them. For instance <code>mdbook-reader patterns builder</code> could print ("<code>man</code>-like") information to the terminal about what is important to know about the builder pattern.</p>
<p>For the organisation side of things:<br>
I see the <a href="https://github.com/rust-essentials/">Rust-essentials</a> org is existing and unused(?) or usage not public. As an idea, we could revive it and collect all the books in there that are essential to building and designing software with Rust with teams that are maintaining each of the repositories.</p>
<p>First thing coming to mind for the API guidelines, for now: I think it could be nice to start having releases of the API guidelines book under SemVer so people can refer to it as in kind of a standardisation process of crate APIs. Maybe even rendering it to pdf and epub and publish it.</p>
<p>So far,<br>
Simon</p>



<a name="222060752"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/219381-t-libs/topic/Rust%20Design%20Patterns/near/222060752" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Ashley Mannix <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Rust.20Design.20Patterns.html#222060752">(Jan 08 2021 at 11:15)</a>:</h4>
<p>Thanks! I’ll go do some more reading through your contributing docs and PRs and get a better idea of what direction you’re taking the book in 🙂</p>
<p>Effectively SemVer’ing the API Guidelines through editions (so call what we currently have the 2018 API Guidelines, and what comes next the 2021 API Guidelines) is something I think would help give it a way to collect and roll out new content and reflect changing idioms. Maybe something like that would work for Patterns too as language changes affect the way you build things.</p>
<p>For platform lock-in... That is a bit of a concern <span aria-label="smile" class="emoji emoji-1f642" role="img" title="smile">:smile:</span> but I think <code>rust-lang</code> is pretty well already very tied to GitHub, so also depending on discussions there probably isn’t a bigger risk than we’re already taking. One of the benefits we get from using GitHub is that it’s very easy to link up issues and PRs in other repos that spawned the discussion in the first place.</p>
<p>But since it’s also easy to migrate issues and things between repos we could just move discussions between the API Guidelines and Patterns if we wanted.</p>
<p>I was thinking once we’ve got ourselves ready for a refresh of the API Guidelines we’d announce a bit of a call for participation on the Rust blog. If we wanted to bring in the Patterns book too we could roll in a call for participation there too?</p>
<p>I think our next step would be defining how the Patterns book would be developed in <code>rust-lang</code> and what involvement we’d expect from the Libs team, and then I guess whether we do want to try establish a Patterns and Guidelines group.</p>



<a name="222067158"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/219381-t-libs/topic/Rust%20Design%20Patterns/near/222067158" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> simonsan <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Rust.20Design.20Patterns.html#222067158">(Jan 08 2021 at 12:35)</a>:</h4>
<p><span class="user-mention silent" data-user-id="204346">Ashley Mannix</span> <a href="#narrow/stream/219381-t-libs/topic/Rust.20Design.20Patterns/near/222060752">said</a>:</p>
<blockquote>
<p>Effectively SemVer’ing the API Guidelines through editions (so call what we currently have the 2018 API Guidelines, and what comes next the 2021 API Guidelines) is something I think would help give it a way to collect and roll out new content and reflect changing idioms. Maybe something like that would work for Patterns too as language changes affect the way you build things.</p>
</blockquote>
<p>That sounds really good! I started a discussion about this in the <a href="https://github.com/rust-unofficial/patterns/discussions/191">patterns repository</a> to see what the input of the community is on that.</p>
<blockquote>
<p>But since it’s also easy to migrate issues and things between repos we could just move discussions between the API Guidelines and Patterns if we wanted.</p>
</blockquote>
<p>I see, that makes it indeed relatively straight forward. <span aria-label="thumbs up" class="emoji emoji-1f44d" role="img" title="thumbs up">:thumbs_up:</span> </p>
<blockquote>
<p>I was thinking once we’ve got ourselves ready for a refresh of the API Guidelines we’d announce a bit of a call for participation on the Rust blog. If we wanted to bring in the Patterns book too we could roll in a call for participation there too?</p>
</blockquote>
<p>Yes, that is a really good idea and would be absolutely lovely! For the patterns repo we'll still need to figure out a bit how to go forward and take a look for the internal repository structure, before a call for participation (ref.: <a href="https://github.com/rust-unofficial/patterns/issues/116">Repository Content (Scope)/TODOs</a>) to make more clear what could be done/is needed.</p>
<blockquote>
<p>I think our next step would be defining how the Patterns book would be developed in <code>rust-lang</code> and what involvement we’d expect from the Libs team, and then I guess whether we do want to try establish a Patterns and Guidelines group.</p>
</blockquote>
<p>Sounds good to me. Just from my side now, to understand it clearly: Is there anything I can help there or is it more on the side wait for further instructions? :)</p>



<a name="222656927"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/219381-t-libs/topic/Rust%20Design%20Patterns/near/222656927" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Ashley Mannix <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Rust.20Design.20Patterns.html#222656927">(Jan 13 2021 at 22:36)</a>:</h4>
<p><span class="user-mention" data-user-id="377077">@simonsan</span> I've started sketching out a proposal to bring Patterns in here: <a href="https://hackmd.io/ENxEJyMhSzirz1U1XQHzbw">https://hackmd.io/ENxEJyMhSzirz1U1XQHzbw</a></p>
<p>I thought one benefit to making it official could be getting input from more of the experts we have floating about in <code>rust-lang</code>. If there's anything you want to add on where you'd like to see the book end up then please feel free to jot them down in the doc there too!</p>



<a name="222790468"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/219381-t-libs/topic/Rust%20Design%20Patterns/near/222790468" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Marco Ieni <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Rust.20Design.20Patterns.html#222790468">(Jan 14 2021 at 21:58)</a>:</h4>
<p>Hi Ashley :)<br>
Regarding the call of participation we are working on labeling some issues as <code>help wanted</code> or <code>good first issue</code>, so in the call of participation you could link to those I think. Just tell us a week or so before, so that we organize the work better :)</p>



<a name="223748405"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/219381-t-libs/topic/Rust%20Design%20Patterns/near/223748405" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> simonsan <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Rust.20Design.20Patterns.html#223748405">(Jan 23 2021 at 12:58)</a>:</h4>
<p><span class="user-mention silent" data-user-id="204346">Ashley Mannix</span> <a href="#narrow/stream/219381-t-libs/topic/Rust.20Design.20Patterns/near/222656927">said</a>:</p>
<blockquote>
<p><span class="user-mention silent" data-user-id="377077">simonsan</span> I've started sketching out a proposal to bring Patterns in here: <a href="https://hackmd.io/ENxEJyMhSzirz1U1XQHzbw">https://hackmd.io/ENxEJyMhSzirz1U1XQHzbw</a></p>
<p>I thought one benefit to making it official could be getting input from more of the experts we have floating about in <code>rust-lang</code>. If there's anything you want to add on where you'd like to see the book end up then please feel free to jot them down in the doc there too!</p>
</blockquote>
<p>Small feedback:<br>
I've read through it when you posted it and I've seen it has been updated since, didn't have much time to add my thoughts still - but will have another look at it this weekend. Thank you for writing that up! <span aria-label="thumbs up" class="emoji emoji-1f44d" role="img" title="thumbs up">:thumbs_up:</span></p>



<a name="223788101"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/219381-t-libs/topic/Rust%20Design%20Patterns/near/223788101" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Ashley Mannix <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Rust.20Design.20Patterns.html#223788101">(Jan 24 2021 at 01:07)</a>:</h4>
<p>Thanks <span class="user-mention" data-user-id="377077">@simonsan</span> <span aria-label="bow" class="emoji emoji-1f647" role="img" title="bow">:bow:</span> I ended up inlining our current proposal for what to do with Guidelines, because I thought you might have some thoughts on that too.</p>
<p>I've had to shift focus a bit so haven't got the time I'd like to dedicate to polishing this up yet. Would you be happy to make any adjustments you'd like and then we can PR it up to our Libs repo, like <a href="https://github.com/rust-lang/libs-team/pull/6">https://github.com/rust-lang/libs-team/pull/6</a> (which it would replace)?</p>



<a name="223852870"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/219381-t-libs/topic/Rust%20Design%20Patterns/near/223852870" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> simonsan <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Rust.20Design.20Patterns.html#223852870">(Jan 25 2021 at 03:48)</a>:</h4>
<p><span class="user-mention silent" data-user-id="204346">Ashley Mannix</span> <a href="#narrow/stream/219381-t-libs/topic/Rust.20Design.20Patterns/near/223788101">said</a>:</p>
<blockquote>
<p>Thanks <span class="user-mention silent" data-user-id="377077">simonsan</span> <span aria-label="bow" class="emoji emoji-1f647" role="img" title="bow">:bow:</span> I ended up inlining our current proposal for what to do with Guidelines, because I thought you might have some thoughts on that too.</p>
<p>I've had to shift focus a bit so haven't got the time I'd like to dedicate to polishing this up yet. Would you be happy to make any adjustments you'd like and then we can PR it up to our Libs repo, like <a href="https://github.com/rust-lang/libs-team/pull/6">https://github.com/rust-lang/libs-team/pull/6</a> (which it would replace)?</p>
</blockquote>
<p>Looks good, really well written! I've added an adjacent sentence and a link to the current <a href="https://github.com/rust-unofficial/patterns/issues/116">umbrella issue</a> which some kind of reflects the current wider scope for people to read into.</p>



<hr><p>Last updated: Aug 07 2021 at 22:04 UTC</p>
</html>